home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Programming / ixemul / sdk / man / cat2 / msgrcv.0 < prev    next >
Encoding:
Text File  |  1998-06-15  |  4.7 KB  |  114 lines
  1.  
  2. MSGRCV(2)                  UNIX Programmer's Manual                  MSGRCV(2)
  3.  
  4. NNAAMMEE
  5.      mmssggrrccvv - receive a message from a message queue
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  9.      ##iinncclluuddee <<ssyyss//iippcc..hh>>
  10.      ##iinncclluuddee <<ssyyss//mmssgg..hh>>
  11.  
  12.      _i_n_t
  13.      mmssggrrccvv(_i_n_t _m_s_q_i_d, _v_o_i_d _*_m_s_g_p, _s_i_z_e___t _m_s_g_s_z, _l_o_n_g _m_s_g_t_y_p, _i_n_t _m_s_g_f_l_g)
  14.  
  15. DDEESSCCRRIIPPTTIIOONN
  16.      The mmssggrrccvv() function receives a message from the message queue specified
  17.      in _m_s_q_i_d, and places it into the structure pointed to by _m_s_g_p. This
  18.      structure should consist of the following members:
  19.  
  20.          long mtype;    /* message type */
  21.          char mtext[1]; /* body of message */
  22.  
  23.      _m_t_y_p_e is an integer greater than 0 that can be used for selecting mes-
  24.      sages, _m_t_e_x_t is an array of bytes, with a size up to that of the system
  25.      limit (MSGMAX).
  26.  
  27.      The value of _m_s_g_t_y_p has one of the following meanings:
  28.  
  29.      ++oo   _m_s_g_t_y_p is greater than 0. The first message of type _m_s_g_t_y_p will be
  30.          received.
  31.  
  32.      ++oo   _m_s_g_t_y_p is equal to 0. The first message on the queue will be re-
  33.          ceived.
  34.  
  35.      ++oo   _m_s_g_t_y_p is less than 0. The first message of the lowest message type
  36.          that is less than or equal to the absolute value of _m_s_g_t_y_p will be
  37.          received.
  38.  
  39.      _m_s_g_s_z specifies the maximum length of the requested message. If the re-
  40.      ceived message has a length greater than _m_s_g_s_z it will be silently trun-
  41.      cated if the MSG_NOERROR flag is set in _m_s_g_f_l_g, otherwise an error will
  42.      be returned.
  43.  
  44.      If no matching message is present on the message queue specified by
  45.      _m_s_q_i_d, the behaviour of mmssggrrccvv() depends on whether the IPC_NOWAIT flag
  46.      is set in _m_s_g_f_l_g or not. If IPC_NOWAIT is set, mmssggrrccvv() will immediately
  47.      return a value of -1, and set _e_r_r_n_o to EAGAIN. If IPC_NOWAIT is not set,
  48.      the calling process will be blocked until:
  49.  
  50.      ++oo   A message of the requested type becomes available on the message
  51.          queue.
  52.  
  53.      ++oo   The message queue is removed, in which case -1 will be returned, and
  54.          _e_r_r_n_o set to EINVAL.
  55.  
  56.      ++oo   A signal is received and caught. -1 is returned, and _e_r_r_n_o set to
  57.          EINTR.
  58.  
  59.      If a message is successfully received, the data structure associated with
  60.      _m_s_q_i_d is updated as follows:
  61.  
  62.      ++oo   _m_s_g___c_b_y_t_e_s is decremented by the size of the message.
  63.  
  64.  
  65.  
  66.      ++oo   _m_s_g___l_r_p_i_d is set to the pid of the caller.
  67.  
  68.      ++oo   _m_s_g___l_r_t_i_m_e is set to the current time.
  69.  
  70.      ++oo   _m_s_g___q_n_u_m is decremented by 1.
  71.  
  72. RREETTUURRNN VVAALLUUEESS
  73.      Upon successful completion, mmssggrrccvv() returns the number of bytes received
  74.      into the _m_t_e_x_t field of the structure pointed to by _m_s_g_p. Otherwise, -1
  75.      is returned, and _e_r_r_n_o set to indicate the error.
  76.  
  77. EERRRROORRSS
  78.      mmssggrrccvv() will fail if:
  79.  
  80.      [EINVAL]      _m_s_q_i_d is not a valid message queue identifier
  81.  
  82.                    The message queue was removed while mmssggrrccvv() was waiting
  83.                    for a message of the requested type to become available on
  84.                    it.
  85.  
  86.                    _m_s_g_s_z is less than 0.
  87.  
  88.      [E2BIG]       A matching message was received, but its size was greater
  89.                    than _m_s_g_s_z and the MSG_NOERROR flag was not set in _m_s_g_f_l_g.
  90.  
  91.      [EACCESS]     The calling process does not have read access to the mes-
  92.                    sage queue.
  93.  
  94.      [EFAULT]      _m_s_g_p points to an invalid address.
  95.  
  96.      [EINTR]       The system call was interrupted by the delivery of a sig-
  97.                    nal.
  98.  
  99.      [EAGAIN]      There is no message of the requested type available on the
  100.                    message queue, and IPC_NOWAIT is set in _m_s_g_f_l_g.
  101.  
  102. SSEEEE AALLSSOO
  103.      msgsnd(2),  msgctl(2),  msgget(2)
  104.  
  105. BBUUGGSS
  106.      NetBSD does not define the EIDRM error value, which should be used in the
  107.      case of a removed message queue, nor the ENOMSG value, which should be
  108.      used when no suitable message is available and IPC_NOWAIT is set.
  109.  
  110. HHIISSTTOORRYY
  111.      Message queues appeared in the first release of AT&T Unix System V.
  112.  
  113.  NetBSD                         August 17, 1995                              2
  114.